配置EasyAR Sense for Android

这篇文章介绍如何使用EasyAR package配置EasyAR非Unity的Android工程。

如果你需要运行EasyAR非Unity的Android样例,请阅读 这篇文章

安装需求

  • JDK 1.8

  • Android SDK Build Tools 至少需要版本30.0.3

  • Android NDK r22

推荐安装最新版本的NDK和SDK

你可以在Eclipse或Android Studio中使用EasyAR。

注意:EasyAR Sense有Java和C++ API,并支持Kotlin,你可以使用最习惯的语言进行开发。

导入EasyAR Sense for Android

使用不同IDE的配置细节可能会有所不同。这里我们只介绍使用gradle和Android Studio 2.2或更新版本的配置方式。

只使用 Java API

  • EasyAR.aar 放入 app/libs 或由gradle配置显示指定的目录。

使用 Java 和 C++ API

  • EasyAR.jar 放入 app/libs 或由gradle配置显示指定的目录。

  • arm64-v8a (和 armeabi-v7a ) 放入 app/src/main/jniLibs 或由gradle配置显示指定的目录。

  • include 中的 easyar 文件夹放入 app/src/main/jni 或由Android.mk 或者 CMakeLists.txt中显示指定的目录。

Gradle Configuration for EasyAR Sense -- Java API

无需特别设置。

Gradle Configuration for EasyAR Sense -- C++ API

可以参考 Google 官方文档 获取更多信息。

Makefile / CMakeLists

这里我们只描述如何配置 Android.mk,如果你偏向于 CMake,可以参考 Google 官方文档

  1. prebuilt library

include $(CLEAR_VARS)
# make sure this path is avaliable for libEasyAR.so
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)
LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so
include $(PREBUILT_SHARED_LIBRARY)
  1. link libEasyAR.so

    GLESv2 是必须加入的。

LOCAL_LDLIBS += -lGLESv2
LOCAL_SHARED_LIBRARIES += EasyAR

External Native Build

android {
    externalNativeBuild {
        ndkBuild {
            path 'src/main/jni/Android.mk'
        }
    }
}

如果你偏向于 CMake,可以参考 Google 官方文档.

指定 ABIs

android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a'
        }
    }
}

如果只需要armeabi-v7a或arm64-v8a,可以在上面只保留其中一个。

在AndroidManifest中添加权限

EasyAR需要以下这些权限,缺少权限将会导致初始化失败并黑屏。

android.permission.CAMERA android.permission.INTERNET

将这些添加到AndroidManifest中。

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="cn.easyar.samples.helloar" >
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

初始化EasyAR

使用 cn.easyar.Engine.initialize 来初始化EasyAR。你可以添加初始化函数到你的activity中如下,

protected void onCreate() {
    Engine.initialize(this, key);
}

其它代码

剩下的就是写EasyAR的逻辑以及其它代码。你可以参考EasyAR的样例来实现。

Windows上文件夹路径长度260字符限制

在Windows上,如果工程中的任意文件(包括生成过程中的临时文件)的绝对路径超过了260字符,在Android Studio中都可能编译失败。此时应减少文件夹长度以绕过此问题。

ARCore

如果使用ARCore,请参考其 官方文档 以配置AndroidManifest和build.gradle。

此外,需要在初始化EasyAR之前。调用

System.loadLibrary("arcore_sdk_c");

使用ARCore v1.19.0之前的版本,在Android 11上将无法被检测到。这是因为Android 11限制了应用对已安装应用的 可见性,需要在Android.manifest中声明。

<queries>
    <package android:name="com.google.ar.core" /> <!-- remove this line after updating to ARCore v1.19.0 or later -->
</queries>

混淆

如果需要对Java代码进行混淆,请排除cn.easyar命名空间。EasyAR Sense中会通过JNI使用类名获取Java类型,如果cn.easyar中的类被改名,将产生未定义行为。

如果使用ProGuard,可以添加

-keep class cn.easyar.** { *; }

或更精确的

-dontwarn javax.annotation.Nonnull
-dontwarn javax.annotation.Nullable
-keepattributes *Annotation*

-keep class cn.easyar.RefBase { native <methods>; }
-keepclassmembers class cn.easyar.* {
    <fields>;
    protected <init>(long, cn.easyar.RefBase);
}
-keep,allowobfuscation interface cn.easyar.FunctorOf* { *; }

-keep class cn.easyar.Buffer { native <methods>; }
-keep class cn.easyar.Engine { native <methods>; }
-keep class cn.easyar.JniUtility { native <methods>; }

-keep class cn.easyar.engine.** { *; }
-keep class cn.easyar.CameraParameters
-keep interface cn.easyar.FunctorOfVoidFromInputFrame

此ProGuard规则已包含在aar库中。

Scoped Storage

Android 10和Android 11中的 Scoped Storage ,会对部分API的使用造成影响。

具体地说,外部路径/sdcard除媒体路径(如/sdcard/Movies)之外的路径无法访问。在Android 10上(而非Android 11上),媒体路径只能通过 MediaStore 访问。

部分需要传入路径的API,如录屏,在Android 10上默认不支持读写媒体路径,但在Android 11上支持。

为了简便,可以在Android 10上使用android:requestLegacyExternalStorage="true"禁用scoped storage。或者只读取/写入内部存储,通过MediaStore与媒体路径进行交换。

Android Gradle plugin

NDK r22默认使用LLD链接器,需要与llvm-strip命令配合,与Android Gradle Plugin 4.0以下版本中自带的strip命令 不兼容

升级到Android Gradle Plugin 4.0,或者使用packagingOptions的doNotStrip选项禁用stripping。